<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
    <head>
        <!-- Book generated using mdBook -->
        <meta charset="UTF-8">
        <title>Setting up a development environment - Discovery</title>


        <!-- Custom HTML head -->
        
        <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
        <meta name="description" content="Discover the world of microcontrollers through Rust">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <meta name="theme-color" content="#ffffff" />

        <link rel="icon" href="../favicon.svg">
        <link rel="shortcut icon" href="../favicon.png">
        <link rel="stylesheet" href="../css/variables.css">
        <link rel="stylesheet" href="../css/general.css">
        <link rel="stylesheet" href="../css/chrome.css">
        <link rel="stylesheet" href="../css/print.css" media="print">

        <!-- Fonts -->
        <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
        <link rel="stylesheet" href="../fonts/fonts.css">

        <!-- Highlight.js Stylesheets -->
        <link rel="stylesheet" href="../highlight.css">
        <link rel="stylesheet" href="../tomorrow-night.css">
        <link rel="stylesheet" href="../ayu-highlight.css">

        <!-- Custom theme stylesheets -->

    </head>
    <body>
        <!-- Provide site root to javascript -->
        <script type="text/javascript">
            var path_to_root = "../";
            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
        </script>

        <!-- Work around some values being stored in localStorage wrapped in quotes -->
        <script type="text/javascript">
            try {
                var theme = localStorage.getItem('mdbook-theme');
                var sidebar = localStorage.getItem('mdbook-sidebar');

                if (theme.startsWith('"') && theme.endsWith('"')) {
                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
                }

                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
                }
            } catch (e) { }
        </script>

        <!-- Set the theme before any content is loaded, prevents flash -->
        <script type="text/javascript">
            var theme;
            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
            if (theme === null || theme === undefined) { theme = default_theme; }
            var html = document.querySelector('html');
            html.classList.remove('no-js')
            html.classList.remove('light')
            html.classList.add(theme);
            html.classList.add('js');
        </script>

        <!-- Hide / unhide sidebar before it is displayed -->
        <script type="text/javascript">
            var html = document.querySelector('html');
            var sidebar = 'hidden';
            if (document.body.clientWidth >= 1080) {
                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
                sidebar = sidebar || 'visible';
            }
            html.classList.remove('sidebar-visible');
            html.classList.add("sidebar-" + sidebar);
        </script>

        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
            <div class="sidebar-scrollbox">
                <ol class="chapter"><li class="chapter-item expanded affix "><a href="../index.html">Introduction</a></li><li class="chapter-item expanded "><a href="../01-background/index.html"><strong aria-hidden="true">1.</strong> Background</a></li><li class="chapter-item expanded "><a href="../02-requirements/index.html"><strong aria-hidden="true">2.</strong> Hardware/knowledge requirements</a></li><li class="chapter-item expanded "><a href="../03-setup/index.html" class="active"><strong aria-hidden="true">3.</strong> Setting up a development environment</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../03-setup/linux.html"><strong aria-hidden="true">3.1.</strong> Linux</a></li><li class="chapter-item expanded "><a href="../03-setup/windows.html"><strong aria-hidden="true">3.2.</strong> Windows</a></li><li class="chapter-item expanded "><a href="../03-setup/macos.html"><strong aria-hidden="true">3.3.</strong> macOS</a></li><li class="chapter-item expanded "><a href="../03-setup/verify.html"><strong aria-hidden="true">3.4.</strong> Verify the installation</a></li></ol></li><li class="chapter-item expanded "><a href="../04-meet-your-hardware/index.html"><strong aria-hidden="true">4.</strong> Meet your hardware</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../04-meet-your-hardware/microbit-v2.html"><strong aria-hidden="true">4.1.</strong> micro:bit v2</a></li><li class="chapter-item expanded "><a href="../04-meet-your-hardware/microbit-v1.html"><strong aria-hidden="true">4.2.</strong> micro:bit v1</a></li><li class="chapter-item expanded "><a href="../04-meet-your-hardware/terminology.html"><strong aria-hidden="true">4.3.</strong> Rust Embedded terminology</a></li></ol></li><li class="chapter-item expanded "><a href="../05-led-roulette/index.html"><strong aria-hidden="true">5.</strong> LED roulette</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../05-led-roulette/build-it.html"><strong aria-hidden="true">5.1.</strong> Build it</a></li><li class="chapter-item expanded "><a href="../05-led-roulette/flash-it.html"><strong aria-hidden="true">5.2.</strong> Flash it</a></li><li class="chapter-item expanded "><a href="../05-led-roulette/debug-it.html"><strong aria-hidden="true">5.3.</strong> Debug it</a></li><li class="chapter-item expanded "><a href="../05-led-roulette/light-it-up.html"><strong aria-hidden="true">5.4.</strong> Light it up</a></li><li class="chapter-item expanded "><a href="../05-led-roulette/it-blinks.html"><strong aria-hidden="true">5.5.</strong> It blinks</a></li><li class="chapter-item expanded "><a href="../05-led-roulette/the-challenge.html"><strong aria-hidden="true">5.6.</strong> The challenge</a></li><li class="chapter-item expanded "><a href="../05-led-roulette/my-solution.html"><strong aria-hidden="true">5.7.</strong> My solution</a></li></ol></li><li class="chapter-item expanded "><a href="../06-serial-communication/index.html"><strong aria-hidden="true">6.</strong> Serial communication</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../06-serial-communication/nix-tooling.html"><strong aria-hidden="true">6.1.</strong> *nix tooling</a></li><li class="chapter-item expanded "><a href="../06-serial-communication/windows-tooling.html"><strong aria-hidden="true">6.2.</strong> Windows tooling</a></li></ol></li><li class="chapter-item expanded "><a href="../07-uart/index.html"><strong aria-hidden="true">7.</strong> UART</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../07-uart/send-a-single-byte.html"><strong aria-hidden="true">7.1.</strong> Send a single byte</a></li><li class="chapter-item expanded "><a href="../07-uart/send-a-string.html"><strong aria-hidden="true">7.2.</strong> Send a string</a></li><li class="chapter-item expanded "><a href="../07-uart/naive-approch-write.html"><strong aria-hidden="true">7.3.</strong> Naive approach and write!</a></li><li class="chapter-item expanded "><a href="../07-uart/receive-a-single-byte.html"><strong aria-hidden="true">7.4.</strong> Receive a single byte</a></li><li class="chapter-item expanded "><a href="../07-uart/echo-server.html"><strong aria-hidden="true">7.5.</strong> Echo server</a></li><li class="chapter-item expanded "><a href="../07-uart/reverse-a-string.html"><strong aria-hidden="true">7.6.</strong> Reverse a string</a></li><li class="chapter-item expanded "><a href="../07-uart/my-solution.html"><strong aria-hidden="true">7.7.</strong> My solution</a></li></ol></li><li class="chapter-item expanded "><a href="../08-i2c/index.html"><strong aria-hidden="true">8.</strong> I2C</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../08-i2c/the-general-protocol.html"><strong aria-hidden="true">8.1.</strong> The general protocol</a></li><li class="chapter-item expanded "><a href="../08-i2c/lsm303agr.html"><strong aria-hidden="true">8.2.</strong> LSM303AGR</a></li><li class="chapter-item expanded "><a href="../08-i2c/read-a-single-register.html"><strong aria-hidden="true">8.3.</strong> Read a single register</a></li><li class="chapter-item expanded "><a href="../08-i2c/using-a-driver.html"><strong aria-hidden="true">8.4.</strong> Using a driver</a></li><li class="chapter-item expanded "><a href="../08-i2c/the-challenge.html"><strong aria-hidden="true">8.5.</strong> The challenge</a></li><li class="chapter-item expanded "><a href="../08-i2c/my-solution.html"><strong aria-hidden="true">8.6.</strong> My solution</a></li></ol></li><li class="chapter-item expanded "><a href="../09-led-compass/index.html"><strong aria-hidden="true">9.</strong> LED compass</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../09-led-compass/calibration.html"><strong aria-hidden="true">9.1.</strong> Calibration</a></li><li class="chapter-item expanded "><a href="../09-led-compass/take-1.html"><strong aria-hidden="true">9.2.</strong> Take 1</a></li><li class="chapter-item expanded "><a href="../09-led-compass/solution-1.html"><strong aria-hidden="true">9.3.</strong> Solution 1</a></li><li class="chapter-item expanded "><a href="../09-led-compass/take-2.html"><strong aria-hidden="true">9.4.</strong> Take 2</a></li><li class="chapter-item expanded "><a href="../09-led-compass/solution-2.html"><strong aria-hidden="true">9.5.</strong> Solution 2</a></li><li class="chapter-item expanded "><a href="../09-led-compass/magnitude.html"><strong aria-hidden="true">9.6.</strong> Magnitude</a></li></ol></li><li class="chapter-item expanded "><a href="../10-punch-o-meter/index.html"><strong aria-hidden="true">10.</strong> Punch-o-meter</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../10-punch-o-meter/gravity-is-up.html"><strong aria-hidden="true">10.1.</strong> Gravity is up?</a></li><li class="chapter-item expanded "><a href="../10-punch-o-meter/the-challenge.html"><strong aria-hidden="true">10.2.</strong> The challenge</a></li><li class="chapter-item expanded "><a href="../10-punch-o-meter/my-solution.html"><strong aria-hidden="true">10.3.</strong> My solution</a></li></ol></li><li class="chapter-item expanded "><a href="../explore.html"><strong aria-hidden="true">11.</strong> What's left for you to explore</a></li><li class="spacer"></li><li class="chapter-item expanded affix "><a href="../appendix/1-general-troubleshooting/index.html">General troubleshooting</a></li><li class="chapter-item expanded affix "><a href="../appendix/2-how-to-use-gdb/index.html">How to use GDB</a></li><li class="spacer"></li></ol>
            </div>
            <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
        </nav>

        <div id="page-wrapper" class="page-wrapper">

            <div class="page">
                                <div id="menu-bar-hover-placeholder"></div>
                <div id="menu-bar" class="menu-bar sticky bordered">
                    <div class="left-buttons">
                        <button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
                            <i class="fa fa-bars"></i>
                        </button>
                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
                            <i class="fa fa-paint-brush"></i>
                        </button>
                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
                            <li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
                        </ul>
                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
                            <i class="fa fa-search"></i>
                        </button>
                    </div>

                    <h1 class="menu-title">Discovery</h1>

                    <div class="right-buttons">
                        <a href="../print.html" title="Print this book" aria-label="Print this book">
                            <i id="print-button" class="fa fa-print"></i>
                        </a>
                        <a href="https://github.com/rust-embedded/discovery/" title="Git repository" aria-label="Git repository">
                            <i id="git-repository-button" class="fa fa-github"></i>
                        </a>

                    </div>
                </div>

                <div id="search-wrapper" class="hidden">
                    <form id="searchbar-outer" class="searchbar-outer">
                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
                    </form>
                    <div id="searchresults-outer" class="searchresults-outer hidden">
                        <div id="searchresults-header" class="searchresults-header"></div>
                        <ul id="searchresults">
                        </ul>
                    </div>
                </div>

                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
                <script type="text/javascript">
                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
                    });
                </script>

                <div id="content" class="content">
                    <main>
                        <h1 id="setting-up-a-development-environment"><a class="header" href="#setting-up-a-development-environment">Setting up a development environment</a></h1>
<p>Dealing with microcontrollers involves several tools as we'll be dealing with an architecture
different from your computer's and we'll have to run and debug programs on a &quot;remote&quot; device.</p>
<h2 id="documentation"><a class="header" href="#documentation">Documentation</a></h2>
<p>Tooling is not everything though. Without documentation, it is pretty much impossible to work with
microcontrollers.</p>
<p>We'll be referring to all these documents throughout this book:</p>
<ul>
<li><a href="https://www.st.com/resource/en/datasheet/lsm303agr.pdf">LSM303AGR</a></li>
</ul>
<h2 id="tools"><a class="header" href="#tools">Tools</a></h2>
<p>We'll use all the tools listed below. Where a minimum version is not specified, any recent version
should work but we have listed the version we have tested.</p>
<ul>
<li>
<p>Rust 1.57.0 or a newer toolchain.</p>
</li>
<li>
<p><code>gdb-multiarch</code>. Tested version: 10.2. Other versions will most likely work as well though
If your distribution/platform does not have <code>gdb-multiarch</code> available <code>arm-none-eabi-gdb</code>
will do the trick as well. Furthermore, some normal <code>gdb</code> binaries are built with multiarch
capabilities as well, you can find further information about this in the sub chapters.</p>
</li>
<li>
<p><a href="https://github.com/rust-embedded/cargo-binutils"><code>cargo-binutils</code></a>. Version 0.3.3 or newer.</p>
</li>
</ul>
<ul>
<li><a href="https://github.com/probe-rs/cargo-embed"><code>cargo-embed</code></a>. Version 0.11.0 or newer.</li>
</ul>
<ul>
<li>
<p><code>minicom</code> on Linux and macOS. Tested version: 2.7.1. Other versions will most likely work as well though</p>
</li>
<li>
<p><code>PuTTY</code> on Windows.</p>
</li>
</ul>
<p>Next, follow OS-agnostic installation instructions for a few of the tools:</p>
<h3 id="rustc--cargo"><a class="header" href="#rustc--cargo"><code>rustc</code> &amp; Cargo</a></h3>
<p>Install rustup by following the instructions at <a href="https://rustup.rs">https://rustup.rs</a>.</p>
<p>If you already have rustup installed double check that you are on the stable
channel and your stable toolchain is up-to-date. <code>rustc -V</code> should return a date
newer than the one shown below:</p>
<pre><code class="language-console">$ rustc -V
rustc 1.53.0 (53cb7b09b 2021-06-17)
</code></pre>
<h3 id="cargo-binutils"><a class="header" href="#cargo-binutils"><code>cargo-binutils</code></a></h3>
<pre><code class="language-console">$ rustup component add llvm-tools-preview

$ cargo install cargo-binutils --vers 0.3.3

$ cargo size --version
cargo-size 0.3.3
</code></pre>
<h3 id="cargo-embed"><a class="header" href="#cargo-embed"><code>cargo-embed</code></a></h3>
<pre><code class="language-console">$ cargo install cargo-embed --vers 0.11.0

$ cargo embed --version
cargo-embed 0.11.0
git commit: crates.io
</code></pre>
<h3 id="this-repository"><a class="header" href="#this-repository">This repository</a></h3>
<p>Since this book also contains some small Rust code bases used in various chapters
you will also have to download its source code. You can do this in one of the following ways:</p>
<ul>
<li>Visit the <a href="https://github.com/rust-embedded/discovery/">repository</a>, click the green &quot;Code&quot; button and then the
&quot;Download Zip&quot; one</li>
<li>Clone it using git (if you know git you presumably already have it installed) from the same repository as linked in
the zip approach</li>
</ul>
<h3 id="os-specific-instructions"><a class="header" href="#os-specific-instructions">OS specific instructions</a></h3>
<p>Now follow the instructions specific to the OS you are using:</p>
<ul>
<li><a href="linux.html">Linux</a></li>
<li><a href="windows.html">Windows</a></li>
<li><a href="macos.html">macOS</a></li>
</ul>

                    </main>

                    <nav class="nav-wrapper" aria-label="Page navigation">
                        <!-- Mobile navigation buttons -->
                            <a rel="prev" href="../02-requirements/index.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                                <i class="fa fa-angle-left"></i>
                            </a>

                            <a rel="next" href="../03-setup/linux.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                                <i class="fa fa-angle-right"></i>
                            </a>

                        <div style="clear: both"></div>
                    </nav>
                </div>
            </div>

            <nav class="nav-wide-wrapper" aria-label="Page navigation">
                    <a rel="prev" href="../02-requirements/index.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                        <i class="fa fa-angle-left"></i>
                    </a>

                    <a rel="next" href="../03-setup/linux.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                        <i class="fa fa-angle-right"></i>
                    </a>
            </nav>

        </div>




        <script type="text/javascript">
            window.playground_copyable = true;
        </script>


        <script src="../elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
        <script src="../mark.min.js" type="text/javascript" charset="utf-8"></script>
        <script src="../searcher.js" type="text/javascript" charset="utf-8"></script>

        <script src="../clipboard.min.js" type="text/javascript" charset="utf-8"></script>
        <script src="../highlight.js" type="text/javascript" charset="utf-8"></script>
        <script src="../book.js" type="text/javascript" charset="utf-8"></script>

        <!-- Custom JS scripts -->


    </body>
</html>
